/*
 * Copyright (C) 2012  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.resources;

import java.io.File;
import java.util.Locale;

/**
 * IResourcesManager : The resources manager interface.
 * 
 * <p>
 * A service implementing this interface provides access to resources:
 * <ul>
 * <li>External files (input files and persisting files)</li>
 * <li>Localized resources (images, messages, etc.)</li>
 * </ul>
 * </p>
 * 
 * @author Romain DUBOIS
 */
public interface IResourcesManager {

    /**
     * Get a file object representing an external data file. It is an 'external'
     * file because it should be persisted even if OSGi cache is cleared. Those
     * 'external' files should be used for export, import or save operations.
     * 
     * <p>
     * Depending on the implementation, each type can define a specific folder
     * and a file extension. Do not rely on a specific file name as the
     * implementation is charge of the (type, name) <-> (filename) mapping.
     * </p>
     * 
     * <p>
     * Be aware that :
     * <ul>
     * <li>The file can be acquired for reading or writing purpose,</li>
     * <li>The file may not exist,</li>
     * <li>The file folder (=parent file) exists.</li>
     * </p>
     * 
     * @param pType
     *            The file type
     * @param pName
     *            The file name
     * @return The file in the persistent folders.
     */
    File getExternalFile(String pType, String pName);

    /**
     * Get a resources node for the default locale.
     * 
     * @param pBaseName
     *            The resources base name
     * @param pType
     *            The resources type
     * @return The resources node, or <code>null</code> if it does not exist.
     * @throws UnsupportedResourceType
     *             If the given <code>pType</code> is not handled.
     */
    <T> IResources<T> getResources(String pBaseName, Class<T> pType) throws UnsupportedResourceType;

    /**
     * Get a resources node for the specified locale.
     * 
     * @param pBaseName
     *            The resources base name
     * @param pType
     *            The resources type
     * @param pLocale
     *            The locale for which the resources node is desired
     * @return The resources node, or <code>null</code> if it does not exist.
     * @throws UnsupportedResourceType
     *             If the given <code>pType</code> is not handled.
     */
    <T> IResources<T> getResources(String pBaseName, Class<T> pType, Locale pLocale)
            throws UnsupportedResourceType;
}
